Date & Time Management

                                  "Poetic justice with her lifted scale;
                                   where, in nice balance, truth with
                                   gold she weighs, and solid pudding
                                   against empty praise."
                                                A Pope, The Duncied 1728

Introduction

          Date manipulation has always been a problem for computer
     programmers. If only there were ten days in a week, ten weeks in a
     year, and ten years in a century! Date mathematics is just plain
     clumsy when you think of dates in terms of days, months, and years.
     Try computing the date one hundred days after February 20, 1965!
     Not so easy.

          Date mathematics is greatly simplified when you convert dates
     into their Julian form. Over the centuries, many mathematicians
     have devised methods of accurately computing dates. Most modern
     computer systems (including this toolkit!) use the Julian system.
     The Julian period was devised in 1582 by Joseph Scaliger, and was
     named after his father Julian (not after the Julian calendar). The
     Julian system assigns each day its own sequential number. Day 1
     began at noon, January 1, 4713 BC. Every day since that time has
     its own sequential number, thus, February 11, 1991 is Julian period
     2448299.

          The GoldDate Unit provides a variety of functions for
     converting dates to and from Julian format. To compute the date one
     hundred days after February 20, 1956, you would convert the date to
     Julian, add one hundred to it, and convert it back to a string.
     This can be achieved with the following compound statement using
     toolkit functions.

          FancyDateStr(GregToJul(2,20,1956)+100,true,true);

          This uses the function GregToJul to convert Month, Day, and
     Year to a Julian period. A hundred is then added to it, and this
     value is passed to the function FancyDateStr, which returns a text
     string showing the date represented by the Julian period. In this
     example, the following date would be returned:

          Wednesday May 30, 1956

          Gold supports dates in eight different formats. Using M, D,
     and Y to represent months, days, and years respectively, the
     supported formats are:

          MMDDYY
          MMDDYYYY
          MMYY
          MMYYYY
          DDMMYY
          DDMMYYYY
          YYMMDD
          YYYYMMDD

          Many of the GoldStr functions need to know in which format the
     date strings are, and so the unit includes the enumerated type
     gDate, which (not surprisingly) has the following members: MMDDYY,
     MMDDYYYY, MMYY, MMYYYY, DDMMYY, DDMMYYYY, YYMMDD, and YYYYMMDD.

          If you plan to delve into ancient history with your date
     calculations, you need to be aware of some strange facts. For
     example, different countries decided to drop certain days to adjust
     for inaccuracies in the lunar calendar. In 1752, the British
     decreed that the following September 2nd would be September 14th.
     Further back in 1582, Pope Gregory XIII (of Gregorian calendar
     fame!) decreed that October 4th would become October 15th. In 1793
     the French ... well, you get the idea. For a good summary of these
     calendar aberrations, refer to any copy of The World Almanac and
     Book of Facts.

Date Methods

     The GoldDate Unit includes the following routines:

     Date:string;

          Returns the system date nicely formatted. The string appears
     as; the Day of Week and Month spelled out followed by the Day, and
     Year.

     GregtoJul(M,D,Y:longint):longint;

     Returns the Julian value (a longint) of a Gregorian date.

     JultoGreg(Jul:longint; var M,D: word; var Y:longint);

     Converts a Julian value to its Gregorian equivalent.

     Day(DStr:string;Format:gDate):word;

     Returns the day portion of a date string.

     Month(DStr:string;Format:gDate):word;

     Returns the month portion of a date string.

     Year(DStr:string;Format:gDate):word;

     Returns the year portion of a date string.

     StrtoJul(DStr:string;Format:gDate):longint;

     Converts a date string to its Julian equivalent.

     DOWNum(DStr:string;Format:gDate):byte;

          Returns a byte indicating the day of the week representative
     of a date string. 0 = Sunday, 1 = Monday, etc .....

     DOWStr(DayByte:byte): string;

          Returns the day of the week, in string form, represented by
     DayByte. 0 = Sunday, 1 = Monday, etc.....

     DOWJul(Jul:longint):byte;

          Returns a byte indicating the day of the week representing the
     Julian value specified. 0 = Sunday, 1 = Monday, etc .....

     GregtoStr(M,D,Y:longint;Format:gDate):string;

          Returns a date string representing the dates indicated by M,
     D, and Y in the form of the enumerated Format.

     JultoStr(Jul:longint;Format:gDate):string;

          Returns a date string in the specified format representing the
     Julian date indicated by Jul.

     TodayinJul:longint;

          Returns a longint value representing the system date in Julian
     form.

     ValidDate(M,D,Y:longint):boolean;

          Returns TRUE if the values passed actually equate to a true
     date. Each value is validated for proper month, day, and year,
     including leap years.

     ValidDateStr(DStr:string;Format:gDate):boolean;

          Returns TRUE if the date string actually equals a true date.
     Each value of the date string is validated for proper month, day,
     and year, including leap years.

     StripDateStr(DStr:string;Format:gDate):string;

     Returns a date string with the date separators removed.

     FancyDateStr(Jul:longint; Long,Day:boolean):string;

          Returns a nicely formatted string representing the indicated
     Julian value. The string is returned in the form of Day-of-week and
     Month spelled out followed by the day and year as numbers.

     RelativeDate(DStr:string;Format:gDate;Delta:longint):string;

          Returns a date string that has been adjusted by the number of
     days indicated by Delta. This may be a positive or negative number
     of days.

     RelativeDateYMD(DStr:string;Format:gDate; Y,M,D:longint):string;

          Returns a date string that has been adjusted by the number of
     years, months, and days. Each offsetting element has the ability to
     be positive or negative.

     StartOfYear(Jul:longint):longint;

          Returns the Julian value of January 1st in the year of the
     date passed.

     EndOfYear(Jul:longint):longint;

          Returns the Julian value of December 31st in the year of the
     date passed.

     DateFormat(Format:gDate):string;

          The date format that is passed must be a member of the
     enumerated type, gDate. If Format is valid, a string representation
     of the date format is returned, otherwise a null string will be
     returned.

     UnformattedDate(InDate:string):string;

     Strips all non-numeric characters.

Time Routines

          Even though the date routines are extremely powerful and offer
     the developer a great deal of flexibility, we thought that a
     complement of time routines was in order. They follow in much the
     same fashion, offering the same power and flexibility within a 24
     hour period.

          Like the date routines, many of the time routines require that
     you specify which time format to use. The enumerated type gTime
     contains the following members: HHMMSS, HHMM.

     Time:string;

          Returns the system time in a nicely formatted string. The time
     string uses a 12 hour clock and is appended with an a.m. or p.m.

     Clock;

          Writes the system time to the screen at a predetermined
     location. Defined within the GoldDate Unit are two variables,
     DateVars.ClockX and DateVars.ClockY which determine the location
     that the system time will be written.

     Hour(TStr:string;Format:gTime):word;

     Returns the hour portion of the specified time string.

     Minute(TStr:string;Format:gTime):word;

     Returns the minute portion of the specified time string.

     Second(TStr:string;Format:gTime):word;

     Returns the second portion of the specified time string.

     TimeStrToLong(TStr:string;Format:gTime):longint;

          Returns a longint value representing the number of seconds
     since midnight until the specified time string.

     LongToTimeStr(Secs:longint;Format:gTime;AmPm,Mltry:boolean):string;

          Returns a time string in the specified format that represents
     the specified number of seconds since midnight. An optional A.M. or
     P.M. may be appended, also the time may optionally be returned in
     military time.

     NowInLong:longint;

          Returns the number of seconds since midnight. This is based on
     the system time.

     ValidTime(Hr,Mn,Sc:longint;Format:gTime;Mltry:boolean):boolean;

          Returns TRUE if Hr, Mn, and Sc are all valid time values. You
     must specify the time format and whether or not you are using
     military time.

     ValidTimeStr(TStr:string;Format:gTime;Mltry:boolean):boolean;

          Returns TRUE if the specified time string is completely valid.
     You must specify the time format and whether or not you are using
     military time.

     StripTimeStr(TStr:string;Format:gTime):string;

     Removes all non-numeric characters from the specified time string.

     TimeToLong(H,M,S:word):longint;

          Converts the hour, minute and second specified to the number
     of seconds since midnight.

     TimeFormat(Format:gTime):string;

          The time format that is passed must be a member of the
     enumerated type, gTime. If Format is valid, a string representation
     of the Time format is returned, otherwise a null string will be
     returned.

     TimeDiff(StartTime, StopTime: longint): longint;

          Returns a longint value representing the number of seconds
     between StartTime and StopTime. If StartTime is greater than
     StopTime, the difference is spanned over midnight.

     LastDateError:integer;

     Returns the code of the last error generated by a GoldDate routine